<!--
  ~ Copyright (C) 2010 Brockmann Consult GmbH (info@brockmann-consult.de)
  ~
  ~ This program is free software; you can redistribute it and/or modify it
  ~ under the terms of the GNU General Public License as published by the Free
  ~ Software Foundation; either version 3 of the License, or (at your option)
  ~ any later version.
  ~ This program is distributed in the hope that it will be useful, but WITHOUT
  ~ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  ~ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
  ~ more details.
  ~
  ~ You should have received a copy of the GNU General Public License along
  ~ with this program; if not, see http://www.gnu.org/licenses/
  -->

<html>
<head>
    <title>Collocation Tool</title>
    <link rel="stylesheet" href="../style.css">
</head>

<body>

<table class="header">
    <tr class="header">
        <td class="header">&nbsp;
            Collocation
        </td>
        <td class="header" align="right"><a href="nbdocs://org.esa.snap.snap.help/org/esa/snap/snap/help/docs/general/overview/SnapOverview.html"><img src="../images/snap_header.jpg" border=0></a>
        </td>
    </tr>
</table>

<h3>Introduction</h3>

<p>
    The <em>Collocation Tool</em> allows to collocate spatially
    overlapping products. Collocating products implies that the pixel
    values of slave products are resampled into the geographical
    raster of the master product.
</p>

<p>
    In order to avoid naming conflicts, the Collocation Tool allows to rename both
    master and slave components such as bands, flag codings and bitmask definitions
    according to a user defined pattern.
</p>

<h3>Algorithm</h3>

<p>
    When products are collocated, a new product is created which contains a
    copy of all components of the master product, i.e. band data, tie-point grids,
    flag codings, bitmask definitions, and metadata. The components of the slave
    products are transfered in a different manner:
</p>

<p>
    The band data of the slave products are resampled into the geographical
    raster of the master product. The user may choose between three different
    resampling methods: <a href="../general/ResamplingMethods.html">Nearest
    Neighbour</a>, <a href="../general/ResamplingMethods.html">Bilinear
    Interpolation</a>, and <a href="../general/ResamplingMethods.html">Cubic
    Convolution</a>. For flag bands and bands where a valid-pixel expression
    is defined, the Nearest Neighbour method is used.
    In order to establish a mapping between the samples in the master and the
    slave rasters, the geographical position of a master sample is used to find
    the corresponding sample in the slave raster. If there is no sample for a
    requested geographical position, the master sample is set to the no-data
    value which was defined for the slave band. The collocation algorithm
    requires accurate geopositioning information for both master and slave
    products. When necessary, accurate geopositioning information may be provided
    by <a href="../visat/GcpManagement.html">ground control points</a>.
</p>

<p>
    As for the master product, the tie-point grids, flag codings and bitmask
    definitions of the slave products are copied. Slave product metadata are not
    transfered.
</p>

<h3>User Interfaces</h3>

<p>
    The Collocation Tool can be invoked from the tool menu in the Sentinel Toolbox
    by selecting <b>Processing->Geometric Operations->Collocation...</b>,
    or in batch mode by using the command line
    tool <i><code>gpt</code></i> (Graph Processing Tool) which is located
    in the <code>bin</code> directory. For the latter type
    <code>gpt Collocate -h</code> for further information.
</p>

<p>
    Selecting the <b>Collocation...</b> command from the Sentinel Toolbox tool menu pops up the
    following dialog:
</p>

<p align="center">
    <img src="images/CollocationDialog.png" alt="Collocation Dialog"/>
</p>

<h5>Source Products Group</h5>

<p class="i1">
    <b>Master:</b>
    Here the user specifies the master product. The combo box presents
    a list of all products opened in the Sentinel Toolbox. The user may select one of these
    or, by clicking on the button next to the combo box, choose a product
    from the file system.
</p>

<p class="i1">
    <b>Slave:</b>
    Here the user specifies the slave products. The user may select products
    opened in SNAP or products from the file system.
</p>

<h5>Target Product Group</h5>

<p class="i1">
    <b>Name:</b>
    Used to specify the name of the target product.
</p>

<p class="i1">
    <b>Save to:</b>
    Used to specify whether the target product should be saved to the file system. The
    combo box presents a list of file formats.
</p>

<p class="i1">
    <b>Open in SNAP:</b>
    Used to specify whether the target product should be opened in the Sentinel Toolbox.
    When the target product is not saved, it is opened in the Sentinel Toolbox automatically.
</p>

<h5>Component Renaming Group</h5>

<p class="i1">
    Each product consists of different components, such as bands, flag codings and
    bitmask definitions. In order to avoid naming conflicts between master and slave
    product components, the user can specify a renaming pattern.
</p>

<p class="i1">
    <b>Rename master components:</b>
    By checking or unchecking this option the automatic renaming of master product
    components can be activated or deactivated, respectively. If activated, all
    components of the master product are renamed according to the
    pattern given in the text field next to the check box. The expression
    <code>${ORIGINAL_NAME}</code> can be used to refer to the original name of the
    component.
</p>

<p class="i1">
    <b>Rename slave components:</b>
    By checking or unchecking this option the automatic renaming of slave product
    components can be activated or deactivated, respectively. If activated, all
    components of the slave products are renamed according to the
    pattern given in the text field next to the check box. The expression
    <code>${ORIGINAL_NAME}</code> or <code>${SLAVE_NUMBER_ID}</code> can be used
    to refer to the original name of the component or the id of the slave (0,1,2...)
    respectively.
</p>

<h5>Resampling Group</h5>

<p class="i1">
    <b>Method:</b>
    The combo box presents several resampling methods:
    <a href="../general/ResamplingMethods.html">Nearest
        Neighbour</a>, <a href="../general/ResamplingMethods.html">Bilinear
    Interpolation</a>, and <a href="../general/ResamplingMethods.html">Cubic
    Convolution</a>. When the slave product contains a band where a valid-pixel
    expression is defined, only the <a href="../general/ResamplingMethods.html">Nearest
    Neighbour</a> method is presented.
</p>

<br>
<hr>
</body>
</html>
